home *** CD-ROM | disk | FTP | other *** search
/ Creative Computers / Creative Computers CD-ROM, Volume 1 (Legendary Design Technologies, Inc.)(1994).iso / commercial / legendary_design / addressit! / req.doc < prev    next >
Text File  |  1994-11-17  |  64KB  |  1,675 lines
  1.  
  2.         The  req.library is a run time re-entrant library that is designed
  3. to  make  it  easier  for  programmers  to  use  powerful, easy to use
  4. requesters  for  communicating  with  users.   The  requester  library
  5. includes  such functions as a color requester, file requester, message
  6. display  requester  and many functions to make the creation of gadgets
  7. for your own custom requesters easier.
  8.  
  9.         Req.library  was  written  by  Colin  Fox (of Pyramyd Designs) and
  10. Bruce  Dawson  (of  CygnusSoft  Software).   Req.library  is  a freely
  11. distributable  library that may be used in commercial products without
  12. paying  any  royalties.  We encourage you to use the requester library
  13. in all of your programs, to make them easier to write, and to use.
  14.  
  15.         Req.library  is  not public domain.  The requester library and all
  16. documentation and example programs are all copyright 1989.
  17.  
  18.         The  requester  library must be distributed with the documentation
  19. file  (req.doc),  and  the  three  include files (req.h, reqbase.h and
  20. reqbase.i).
  21.  
  22.  
  23.  
  24.         Req.library  is  dedicated  to  the programmers who make the Amiga
  25. shine the way it was meant to.
  26.  
  27.  
  28. OverView:
  29.  
  30.         All  of  the  req.library functions that bring up requesters allow
  31. you two ways of specifying what screen you would like the requester to
  32. appear  on.  The first way is the more efficient way, because you only
  33. have  to set it up once and then it takes care of things automatially.
  34. There  is  a  field in all process structures called the pr_WindowPtr.
  35. This  pointer  is  used by DOS to decide where to put it's requesters.
  36. If  pr_WindowPtr  contains  a  zero,  requesters  go  on the workbench
  37. screen.  If it contains the address of a window, then requesters go on
  38. that  window's  screen.   If  it  contains a negative one, then no DOS
  39. requesters come up.  The req.library requesters all use this variable,
  40. if  they  are  called from a process .  However, if the pointer is -1,
  41. the req.library functions do still appear, on the workbench screen.
  42.  
  43.         The  second  way  was  put in mainly so that the requesters can be
  44. called from tasks.  Since a task does not have a process structure, it
  45. also  lacks a pr_WindowPtr.  Therefore, all of the requester functions
  46. which  can  be  used from a task (currently everything except the file
  47. requester) can be passed a window pointer, either as a parameter or as
  48. an  element in a structure.  Important:  This pointer takes precedence
  49. over  the  pr_WindowPtr  so  if  you  wish  the  requesters to use the
  50. pr_WindowPtr  you  must  zero  the window fields that the routines are
  51. expecting.   In  the case of fields in a structure this can be easy as
  52. long   as  you  make  sure  your  structure  defaults  to  being  zero
  53. everywhere.
  54.  
  55.         Setting  the  pr_WindowPtr is quite a simple matter.  All you have
  56. to do is do a FindTask((char *)0); which returns a pointer to your own
  57. task  and your own process (a task structure is the first element of a
  58. process  structure).   Then  you  simply  preserve  the  old  value of
  59. pr_WindowPtr (VERY IMPORTANT!!!) and put a window pointer into it.
  60.  
  61. eg:
  62.                                 /* Find my task. */
  63.         myprocess = (struct Process *)FindTask((char *)0);
  64.         oldwindowptr = myprocess->pr_WindowPtr;
  65.         myprocess->pr_WindowPtr = window;
  66.  
  67. or:
  68.  
  69.         MOVE.L  4,A6
  70.         MOVE.L  #0,A1
  71.         SYS             FindTask        ;Find my task.
  72.         MOVE.L  D0,_myprocess
  73.         MOVE.L  D0,A0
  74.         MOVE.L  pr_WindowPtr(A0),_oldwindowptr
  75.         MOVE.L  _window,pr_WindowPtr(A0)
  76.  
  77.         Before your program exits it is VERY important that it restore the
  78. previous  value of pr_WindowPtr.  If you don't, then your program will
  79. work  in some situations, but will BLOW UP in others.  For example, if
  80. you  execute  (without  using the 'run' command) a program, which then
  81. sets  the  pr_WindowPtr  to  point at one of its windows and the exits
  82. without  restoring  it,  then  the  next time a DOS requester tries to
  83. appear...  BOOM!  The machine will probably crash as DOS tries to open
  84. a requester on a now closed screen.  Therefore, before leaving:
  85.  
  86.         myprocess->pr_WindowPtr = oldwindowptr;
  87.  
  88. or:
  89.  
  90.         MOVE.L  _myprocess,A0
  91.         MOVE.L  _oldwindowptr,pr_WindowPtr(A0)
  92.  
  93.  
  94.  
  95.         One  final  note.   The  pr_WindowPtr  field exists in the process
  96. structure.   This  means  that  a  task  does  not  have  this  field.
  97. Therefore,  if you want to call one of the requester library functions
  98. from  a  task,  you  will not be able to specify what screen you would
  99. like  the  requester  to  appear on by setting the pr_WindowPtr field.
  100. All  of  the  functions  that open requesters and can be called from a
  101. task  (the file requester/font requester is the only one that can't be
  102. called  froma task) have some other way of specifying which screen you
  103. would like them to open on.  They will have either have a field in the
  104. structure  which you must pass them or a parameter which can contain a
  105. window  pointer  to one of the windows on your custom screen.  If this
  106. pointer is non-zero then it overrides the pr_WindowPtr field.
  107.  
  108.  
  109.  
  110.  
  111.         By  opening the requester library, you not only gain access to all
  112. of  the functions documented below, but to some other goodies as well.
  113. Req.library   needs  and  therefore  opens  several  other  libraries,
  114. including  dos.library,  intuition.library,  graphics.library  and the
  115. console  device.   All  of  these  pointers  are  stored in the ReqLib
  116. structure  which  you  get a pointer to when you open the req.library.
  117. Therefore,  you  can  save  yourself  a little bit of code by grabbing
  118. these  fields  after opening the requester library.  The only thing to
  119. beware of is don't use these values after you have close the requester
  120. library,  because  at  that point there is no guarantee that they will
  121. still be valid.
  122.  
  123.         In  addition  to  these  libraries,  the Images pointer in the req
  124. library structure points to a set of ten small images (four arrows and
  125. ssix  letters)  which have are guaranteed to be in chip memory.  These
  126. can be used if your program requires this type of images.
  127.  
  128.  
  129.  
  130.  
  131.         One  thing to keep in mind when using the gadget creation routines
  132. is  that there isn't any way for us to check that you have passed us a
  133. pointer  to  the  correct size of buffer, so you _must_ make sure that
  134. you are allocating the right amount of memory.
  135.  
  136.  
  137. --------------------------------------------------------------
  138. Here's a quick list of the functions available:
  139. --------------------------------------------------------------
  140.  
  141. Center..................Center a new window over the mouse.
  142.  
  143. SetSize.................Prop gadget handling routines (32 bit)
  144. SetLocation
  145. ReadLocation
  146.  
  147. Format..................sprintf() format routine
  148.  
  149. SimpleRequest...........Starter gluecode to TextRequest- Single gadget
  150. TwoGadRequest...........Starter gluecode to TextRequest- Two gadgets
  151.  
  152. FileRequester...........FileRequester routines
  153. PurgeFiles
  154.  
  155. ColorRequester..........a colorrequester
  156.  
  157. MakeGadget..............Gadget creation routines
  158. MakeString
  159. MakeProp
  160. MakeButton
  161.  
  162. MakeScrollBar...........3   part   gadget;   2   arrows  and  a  prop.
  163.                                                 Horizontal or Vertical
  164.  
  165. LinkGadget..............Gadget  creation  routines that self-hook into
  166.                                                 the newwindow
  167. LinkStringGadget........gadget list.
  168. LinkPropGadget
  169.  
  170. DrawBox.................Draw a box (x1y1)(x2y2) in one command
  171.  
  172. GetFontHeightAndWidth...return height and width of current font
  173.  
  174. RealTimeScroll..........scroll routine used in file requester
  175.  
  176. TextRequest.............Powerful requester function
  177.  
  178. GetString...............Get a line of text from the user
  179. GetLong.................Get a signed long from the user
  180.  
  181. RawKeyToAscii...........Convert raw key to ascii
  182.  
  183. NewGetString            A second point to GetString.  Different way of
  184.                         passing parameters.
  185.  
  186. ----------------------------------------------------------------
  187.  
  188.  
  189. NAME
  190.                 Center
  191.  
  192.  
  193. SYNOPSIS
  194.                 Center( &nw, x, y)
  195.                          A0 D0 D1
  196.  
  197. struct NewWindow *nw;
  198. USHORT x,y;
  199.  
  200. DESCRIPTION
  201.  
  202.         Center()  is  used  to